ITK Programmer's Guide

 

Table of contents | Intro | General | TCP Low Level | TCP High Level | UDP | DNS | PPP
Encoding/Decoding | Internet Config | Goodies | Cryptography | Appendix

 

Chapter 4 : Higher-level TCP/IP routines

   

   

Chapter contents:

About this chapter...

This chapter describes high level TCP/IP routines provided by ITK.

These routines allow some more sophisticated using of TCP streams.

   

   

ITK_TCPSendFile

Syntax:

result := ITK_TCPSendFile(streamRef;pathname;filterFlag;sendBlockSize;startOffset;endOffset)

Description:

Sends a file through a TCP stream. Under MacOS, only the data fork of the file is sent.
After sending the file, the stream is left opened.
Filtering can be applied on the sent file.

The last two parameters allow to send only a portion of the file.

ITK's internal buffer is flushed before sending the file.

Params:

In/Out

Parameter

Type

   

Example or note
->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen.
->

pathname

Text

pathname of the file to send

Under Windows, the full pathname must be passed, ex: "C:\MYSTUFF\MYFILE.TXT".  
->

filterFlag

Longint

 

   

One or more encodings can be applied before sending the data (or putting it into ITK's receive buffer). You may add flag values to apply several filters at once.
See Table#1 for all filter flag values.
->

sendBlockSize

Longint

send block size (byte count for I/O operations, leave to 0 to use default value)

This parameter tells ITK which size to use for each data block read from the file and send through the stream.
->

startOffset

Longint

starting offset of the portion of the file to send, leave 0 to start at the beginning of the file.

Offsets in the file are starting at 0, so the second byte of the file has its offset equal to 1, etc.
->

endOffset

Longint

ending offset of the portion of the file to send, leave 0 to send up to the end of the file.

See above.
<-

result

Longint

   

Negative values indicate that an error occurred on the stream (it may have been released by the remote host).

Example:

 
$stream := ITK_TCPOpen("host.domain.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPSendFile($stream;"C:\MYFILE.TXT")
  ...
 
Back to top

ITK_TCPRecvFile

Syntax:

result := ITK_TCPRecvFile(streamRef;pathname;filterFlag;optFlag;timeout)

Description:

Stores all data received on a TCP stream into a file.
ITK_TCPRcvFile returns control when:

  • the stream is closed by the remote host,
  • no data has been received during the timeout value,
  • an error occurred on the stream or on the file (I/O error, disk full, etc.).

Filtering can be applied on the received file.

The stream is automatically released before returning control to 4D unless the option flags are set to keep the stream (see optFlag below).

Params:

In/Out

Parameter

Type

   

Example or note
->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen.
->

pathname

Text

pathname of the file to use to store incoming data

Under Windows, the full pathname must be passed, ex: "C:\MYSTUFF\MYFILE.TXT".   
->

filterFlag

Longint

 

   

One or more encodings can be applied before sending the data (or putting it into ITK's receive buffer). You may add flag values to apply several filters at once.
See Table#1 for all filter flag values.
->

optFlag

Longint

Values:

  • 1 = append to existing file
  • 2 = do not release the stream

One or more options can be requested. You may add flag values to apply several options at once.

Ex: 0 = nothing special
3 = append to existing file and do not release the stream
->

timeout

Longint

Timeout value in seconds

0 = infinite time
<-

result

Longint

Negative values indicate that an error occurred.

Example:

 
$stream := ITK_TCPOpen("host.domain.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPRecvFile($stream;"C:\MYFILE.TXT") `
End If
Back to top

ITK_TCPSendPict

Syntax:

result := ITK_TCPSendPict(streamRef;picture;startOffset;endOffset)

Description:

Sends a picture content or a part of it through an established TCP stream.
ITK_TCPSendPict will look for GIF or JPEG data and only send them if present in the picture.

In that case, the picture must already be JPEG or GIF compressed, for example:

COMPRESS PICTURE($myPict;"jpeg";500) 
$err := ITK_TCPSendPict($stream;$myPict) 
 

or

$err := ITK_TCPSendPict($stream;ITK_Pict2GIF($myPict))

Params:

In/Out

Parameter

Type

   

Example or note
->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen.
->

picture

Picture

Picture to send

   
->

startOffset

Longint

Starting offset of data to send

Pass 0 to send data from the beginning of the picture.
->

endOffset

Longint

Ending offset of data to send

Pass -1 to send the full content of the picture without looking for GIF or JPEG data.
<-

result

Longint

   

Negative values indicates that an error occurred on this stream (it may have been released by the remote host).

Example:

 
COMPRESS PICTURE($myPict;"jpeg";500) 
$err := ITK_TCPSendPict($stream;$myPict) 
 

or

$err := ITK_TCPSendPict($stream;ITK_Pict2GIF($myPict)) 
 
Back to top

ITK_TCPSendBlob

Syntax:

result := ITK_TCPSendBlob(streamRef;blob;flushFlag;filterFlag;startOffset;endOffset)

Description:

Sends a blob content or a part of it through an established TCP stream.
ITK has its own send buffer which help reducing the number of calls to lower level TCP/IP layers when small chunks of data are sent.
Filtering can be applied on the sent data.

Params:

In/Out

Parameter

Type

   

Example or note
->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen.
->

blob

Blob

data to send

   
->

flushFlag

Longint

 

   

0 = don't use ITK send buffer, flush its content if it wasn't empty,
1 = use ITK send buffer. It will be flushed regularly by ITK.
Values above 255 indicate the maximum number of bytes that may be buffered. If the send buffer contains more than the value passed, ITK will flush its send buffer.
ITK's send buffer will also be flushed when calling ITK_TCPRcv or ITK_TCPClose.
->

filterFlag

Longint

   

One or more encoding can be applied before sending the data (or putting them in ITK's send buffer). You may add flag value to apply several filters at once.
See Table#1 for all filter flag values.
->

startOffset

Longint

Starting offset of data to send

Pass 0 to send data from the beginning of the blob.
->

endOffset

Longint

Ending offset of data to send

Pass 0 to send data up to the end of the blob.
<-

result

Longint

   

Returns the number of bytes currently store in ITK's send buffer upon return.

Negative values indicates that an error occurred on this stream (it may have been released by the remote host).

Example:

 
$stream := ITK_TCPOpen("www.internet-toolkit.com";80)
If ($stream#0)
  ... ` wait for connection to be established
  $err := ITK_TCPSendBlob($stream;myBlob)   ` send the whole blob content
  $err := ITK_TCPSendBlob($stream;myBlob;0;0;0;1024) ` send first 1024 bytes of the blob
  ...
 
Back to top

ITK_TCPRecvBlob

Syntax:

result := ITK_TCPRecvBlob(streamRef;dataStorage;maxLen;filterFlag;appendFlag;endString;timeout)

Description:

Receives data through an established TCP stream.
Remaining data in ITK's send buffer are sent if present.
Filtering can be applied on the received text.

ITK_TCPRecvBlob will return control:

  • immediately if endString is empty
  • when endString is received
  • when maxLen bytes have been received
  • after timeout has expired

Params:

In/Out

Parameter

Type

   

Example or note
->

 

streamRef

 

Longint

 

stream reference number

As returned by ITK_TCPOpen or ITK_TCPListen.
->

dataStorage

Blob

storage variable or field

Content is replaced or appended depending on appendFlag
->

maxLen

Longint

 

maximum length of to be received

Pass 0 if you want to receive all available data (up to 32000 bytes which is the limit for Text value in 4D).
->

filterFlag

Longint

   

One or more encoding can be applied before sending the data (or put them in ITK's send buffer). You may add flag value to apply several filters at once.
See Table#1 for all filter flag values.
->

appendFlag

Longint

 

   

0 = do not append received data to previous data present in dataStorage
1 = append received data to previous data present in dataStorage
->

endString

Text

end receive string

ITK_TCPRcv will return data until this string is found. If this string is found in incoming data, ITK_TCPRcv will return all data up to this string, remaining data will be kept in ITK's receive buffer.
->

timeout

Longint

maximum time to wait for endString (in 1/60th of a second)

Special values:
-1 = infinite time
0 = no timeout, returns control immediately
<-

result

Longint

returns number of bytes received or any error code (negative value).

-1 = invalid stream reference number

Example:

 
$stream := ITK_TCPOpen("mail.internet-toolkit.com";25)
if ($stream#0)
  ... ` wait for connection to be established
  $result := ITK_TCPRecvBlob($stream; $myBlob) ` receive available data in a blob
  ...
 
Back to top

CQ/27-May-98